home *** CD-ROM | disk | FTP | other *** search
/ Beginning Mac Programming / Beginning Mac Programming.bin / Open Me for REALbasic 3 / REALbasic 3.2 / Example Projects / Reusable Classes_Code / Internet_Networking / FTP Socket / REALbasic FTP How To < prev    next >
Text File  |  1998-08-25  |  12KB  |  154 lines
  1. FTP Socket Subclass
  2. 1.0
  3.  
  4. © 1998 Brian F. Jones
  5. brjones@hiwaay.net
  6. http://fly.hiwaay.net/~brjones/
  7.  
  8. These socket subclasses are intended for use in programming with REALbasic, from Andrew Barry and REAL Software <http://www.realsoftware.com/>.
  9.  
  10. Special licencing statement:
  11. The code included in the socket subclasses and demonstration projects may be used in personal projects for free.  This code may be used in commercial projects at a fee to be determined by various factors such as distribution and level of support.  Please contact brjones@hiwaay.net for fee negotiation.
  12.  
  13. Regardless of  the project, I request acknowledgement of my work, and a copy of any application which uses these subclasses.
  14.  
  15. This work may be redistributed with this file and all parts of the original distribution intact and unchanged.
  16.  
  17. What's Included:
  18.  
  19. ftpCommandSocket
  20. This is the socket subclass that controls the ftp session.  Most interaction is done with this control class.
  21.  
  22. ftpDataSocket
  23. This is the socket subclass that transfers the actual data.  It is controled by the command socket, but fires some useful events.
  24.  
  25. uploadThread
  26. This is the thread class used to upload files.   This is necessary to keep the upload loop from locking the computer up until the upload is complete.  You do not interface with this thread subclass.
  27.  
  28. Demo's
  29. There are two demo projects included with the subclasses.  These demonstrate how to set up and use the ftp subclasses your own project.
  30.  
  31.  
  32. Instructions:
  33.  
  34. The Set-up:
  35. General notes: For any file transfer to occur, you must include both the ftpCommandSocket and ftpDataSocket subclasses in your project.   The ftpCommandSocket subclass requires a pointer to an instance of the ftpDataSocket before transferring any data (step 3 below).
  36.  
  37. 1) First you will want to drag the two socket subclasses into your project window.  Make sure their super is set to Socket in the Properties window.  Also drag the uploadThread class into your project.  Do not change the names of any of these classes.
  38.  
  39. 2) Next, create two socket controls from the tools pallette in a window.  By default, their super will be Socket, so you must change them.  Select one and change its super in the properties window to ftpCommandSocket, and change its name to something meaningful, such as comSock.  Then select the other socket control, and change its super to ftpDataSocket.  Also give this socket control a meaningful name such as dataSock.
  40.  
  41. 3) Place a pointer to the ftpDataSocket instance in your ftpCommandSocket control.  This must be done somewhere in code that gets executed before you attempt to open any connection.  The ftpCommandSocket variable that holds this pointer is called dataPort.  If you named the instances comSock and dataSock as above, then the statement would be:
  42.  
  43.             comSock.dataPort = dataSock
  44.  
  45. This is very important, as the command socket needs to be able to communicate with the data socket.  Your app will probably crash if you don't do this.
  46.  
  47. File Transfer:
  48. You are now ready to log in and transfer files.  If you simply have one file to transfer, there are built in commands for this.
  49.  
  50. Simple transfers:
  51. To upload a single file, use the ftpCommandSocket method uploadOneFile.
  52. The analogous method to download a file is called downloadOneFile.
  53. Both commands complete the transaction, and then disconnect from the server. See the ftp-demo.π  project for a simple demonstration of these commands.
  54.  
  55.             Sub uploadOneFile(serverAddress as string, userName as string, password as string,  localFilePath as string,
  56.                                                                             remotePath as string, fileType as string, usePASV as boolean)
  57.  
  58.             Sub downloadOneFile(serverAddress as string, userName as string, password as string,  localFilePath as string,
  59.                                                                             remotePath as string, fileType as string, usePASV as boolean, macType as string, macCreator as string)
  60.  
  61. ServerAddress is the IP address or domain name of the ftp server you wish to connect to.
  62. UserName is your username on that server.  If using anonomous ftp, username should be "ftp."
  63. Password is of course your password.  If using anonomous ftp, password should be your email address.
  64. LocalFilePath is the path to a local file to upload, or the path you wish to save a downloaded file to.  If you are downloading a file, and wish to prompt the user for a name, send a blank string ("") here and the socket subclasses will do this for you.
  65. RemotePath is the path to a directory for file uploads (leaving this blank indicates an upload to the default directory upon logging in), or the path to a file on the remote server.  If the file you wish to download is in the default ftp directory, then just put the name of the file here.
  66. FileType is not the Macintosh file type.  This variable is used to determine the type of data transferred, whether it is ascii text (type "A") or binary data (type "I").  No other types are valid in this implimentation.
  67. UsePASV is a boolean flag that tells the subclasses you wish to use the PASV command to establish the data connection rather than PORT.  PASV is probably required if you are behind a firewall using a proxy.  Otherwise, it doesn't really matter which you choose.
  68. MacType  This is the four letter Mac file type code.
  69. MacCreator This is the four letter Mac creator code.
  70.  
  71. Interactive Sessions:
  72. For those who wish to transfer more than a single file in a session, or desire more interactivity… you're in luck!
  73.  
  74. The socket subclasses were designed to log in automatically after establishing a connection with the server.  Some configuration is required before this can happen if not using the above simple transfer commands.  After logging in to the server, there are some predefined methods for doing standard ftp tasks, such as transferring and deleting files, getting file lists, etc…
  75.  
  76. General configuration for interactive sessions:
  77.  
  78. There are several internal variables that must be configured before establishing a connection to the ftp server.  These variables are held in your instance of the ftpCommandSocket.  For the purposes of this document, we'll assume you named your command socket and data socket instances comSock and DataSock as above in the set up instructions.
  79.  
  80. Before connecting to a server, you must first configure the following  ftpCommandSocket instance variables in your code (these are not necessary if using the simple transfer methods above):
  81.  
  82. address The ip address or domain name of the ftp server (eg. comSock.address = "ftp.fyisoftware.com").
  83. port  The port number for ftp connections is usually 21.  This can be set in the command socket properties window or in code (eg. comSock.port = 21).
  84. userID The account name you wish to access, for anonomous ftp, simply use "ftp" (eg. comSock.userID = "ftp").
  85. password The password for the account; use your email address for anonomous access.
  86. usePASV Boolean flag for using the PASV or PORT commands.  See explanation above under Simple Transfers (eg. comSock.usePASV = false)
  87. dataPort The reference to the data socket instance.  (eg. comSock.dataPort = dataSock)
  88.  
  89. After configuring the instance variables, just call connect (eg. comSock.connect).  This attempts to establish the connection with the server and automatically sends the userID and password to log in.
  90.  
  91. There are several ftpCommandSocket and ftpDataSocket events (in addition to the standard socket events) which will be useful. 
  92.  
  93. Special ftpCommandSocket events:
  94.  
  95. LoggedIn(response as string)  Called when sucessfully logged into the server. The server response here contains the current remote path (the ftpCommandSocket subclass issues a "PWD" command before firing this event).
  96. GotResponse(response as string)  Called when the server sends data to the command socket. The variable response contains the text of the server message.
  97. GotServerError(error as string)  Called when the server response contains an error code.  The error returned is the entire response string from the server.
  98. RemoteDirChanged(response as string)  Called when the remote path has been sucessfully changed.  The response contains the new path.
  99.  
  100. Special ftpDataSocket events:
  101.  
  102. GotList(data as string)  Called when a list is sucessfully received from the server.  It's up to you to parse the data, however, there is an example in the ftpClient demo included.
  103. FileTransferComplete()  Called when a file has been sucessfully transfered.
  104. BytesTransfered(bytes as integer)  Called when data is received by or written to the data socket.
  105.  
  106. The methods for managing files all reside in the ftpCommandSocket.
  107.  
  108. Available ftpCommandSocket methods are as follows:
  109.  
  110. GetList() Sends a LIST command to the server.  The list is returned in the GotList event of the data socket.
  111. GetDirList(path as string)  Sends a LIST <path> command to the server.  This is used to list a directory that is not the current working directory.  The list is returned in the GotList event of the data socket.
  112. GetNlst()  Send an NLST command to the server.  The name list is returned in the GotList event of the data socket.
  113. GetFile(remotePath as string, localPath as string, type as string, macType as string, macCreator as string)  Sends an RETR command.  The remotePath file is downloaded and saved to localPath.  Remote paths may be absolute or relative to the current working directory.  If the localPath is not indicated, then the command socket will prompt you for a filename.  Type is either "A" for ascii files, or "I" for binary data. MacType and MacCreator are the four letter type codes to be assigned to the downloaded file.  The data socket FileTransferComplete event is fired when the file transfer is complete.
  114. StorFile(localPath as string, remotePath as string, type as string)  Used to upload files to the server.  RemotePath may be an absolute path including the filename, or just the filename to place it in the default directory.  The localPath variable must point to a valid local file.  Type is either "A" for ascii files, or "I" for binary data.
  115. StorString(data as string, remotePath as string, type as string)  Creates a file on the server at the remotePath location with the data string content.  RemotePath may be an absolute path including the filename, or just the filename to place it in the default directory.  Type is either "A" for ascii files, or "I" for binary data.
  116. deleteFile(path as string)  Deletes the file indicated by path.
  117. makeDirectory(path as string)  Creates a new directory indicated by path.
  118. sendCWD(path as string)  Changes the remote directory to the one specified by path.
  119. sendPWD()  Returns the current remote directory path (in the GotResponse event).
  120. sendQUIT()  Sends the quit command to the remote server.
  121. sendSYST()  Sends the SYST command.  The server OS is returned in the gotResponse event.
  122.  
  123. There are no ftpDataSocket methods that are intended to be used by the programmer.
  124.  
  125.  
  126. Gotcha's
  127.  
  128. Once again, make certain you create a pointer to the data socket in the command socket (comSock.dataPort = dataSock).
  129.  
  130. This code has been tested with REALbasic 1.0F7.  REALbasic sockets sometimes appear to return from the listen method and continue executing code before the socket is fully listening.  This can cause problems using PORT on faster machines and networks, since the server may attempt to connect to the client before the socket it ready.  If you notice this problem, try using PASV connections instead.
  131.  
  132. If you are replacing older FTP socket subclasses with these, then after dragging the class definitions into your project window but before doing anything else, make sure your socket controls have their super set properly.  I've noticed problems (crashes) with DR1r33 not remembering the correct super when changing the class definition, and something as simple as trying to save the project without resetting this can cause a crash.
  133.  
  134. If you run into problems or think you found a bug, please let me know.
  135.  
  136.  
  137. Revision History:
  138.  
  139. Version 1.0 final
  140. • Fixed problem with threaded uploads
  141.  
  142. Version 1.0b3
  143. • Added threading for uploads
  144. • Added the GetDirList command
  145. • Revised the upload of text files to be more efficient
  146. • Major additions to the FTP client demo
  147.  
  148. Version 1.0b2
  149. • Added ability to create files with a specified type and creator
  150. • Fixed a bug with creating a folderitem in the command socket subclass
  151. • Updated the ftp demonstrations
  152.  
  153. Version 1.0b1
  154. • First public release